home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / c / asmlib35.zip / GRAPHICS.DOC < prev    next >
Text File  |  1993-01-20  |  57KB  |  1,609 lines
  1.  
  2. ****************************** GRAPHICS *************************************
  3.  
  4. ASMLIB Graphics (C) Copyright 1991 - 1993 Douglas Herr
  5. All rights reserved
  6.  
  7. ASMLIB recognizes and automatically supports several graphics modes,
  8. including several which are not recognized by IBM's BIOS.  You should
  9. assume that all ASMLIB graphics subroutines write directly to the video
  10. hardware.  IMPORTANT: ALL ASMLIB GRAPHICS SUBROUTINES ASSUME DS:@DATA.
  11.  
  12. Locations on Graphics screens are defined by coordinate pairs such as (x,y).
  13. X-coordinates are the horizontal dimensions of the screen, and Y-coordinates
  14. are the vertical coordinates.  X = 0 is the at the left edge of the screen,
  15. and X = 719 is the right edge of a Hercules screen, while Y = 0 is the top
  16. edge of the screen and Y = 347 is the bottom (Hercules).  Thus, the
  17. coordinate specified by (719,0) is the extreme upper right corner of a
  18. Hercules screen.
  19.  
  20. Graphics subroutines as powerful and flexible as ASMLIB's can be quite
  21. large.  If you have licenced ASMLIB source code, you can use several
  22. pre-defined conditional assembly directives to eliminate code from
  23. ASMLIB object files if you do not want or need to support all graphics
  24. modes:
  25.  
  26.         NOHERC      eliminates all Hercules and InColor code
  27.         NOINCOLOR   eliminates code for the InColor card
  28.                (InColor works with Hercules monochrome code in 2 colors)
  29.         NO256       eliminates code for the three 256-color modes
  30.         NOCGA       eliminates code for CGA graphics modes
  31.         NOMCGA      elimiates code for MCGA mode 11h
  32.         NOLPATTERN  elimiates code for non-solid lines (in DRAWLINE.ASM)
  33.  
  34. for example, if you want line drawing programs to use only EGA/VGA-type
  35. 16-color modes, assemble DRAWLINE.ASM like this:
  36.  
  37.          C:\MASM\>masm /dnoherc /dnocga /dnovga256 /dnomcga drawline;
  38.  
  39. this reduces the size of drawline.obj significantly and speeds its
  40. operation somewhat.
  41.  
  42. BitBlock subroutines in ASMHUGE.LIB work with huge data blocks (larger
  43. than 64k).  This permits entire EGA, VGA or InColor screens to be saved
  44. in one block if sufficient RAM is available.
  45.  
  46.  
  47. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  48.  
  49. Graphics modes and pages supported are:
  50.  
  51. Mode           Maximum x   Maximum y   Colors  Pages (1)  Equipment
  52.                 ("xmax")    ("ymax")
  53.  
  54. HGraph           719          347       2         0, 1    HGC, HGC+ (2)
  55. HGraph           719          347      16         0, 1    InColor  (2)
  56. 04h, 05h         319          199       4         0       CGA, EGA, MCGA, VGA
  57. 06h              639          199       2         0       CGA, EGA, MCGA, VGA
  58. 0Dh              319          199       16        0 - 7   EGA, VGA  (3)
  59. 0Eh              639          199       16        0 - 3   EGA, VGA  (3)
  60. 0Fh              639          349       4         0       EGA, VGA  (4)
  61. 10h              639          349       16        0, 1    EGA, VGA  (3,5)
  62. 11h              639          479       2         0       MCGA, VGA
  63. 12h              639          479       16        0       VGA
  64. 13h              319          199       256       0       MCGA, VGA
  65. 40h              639          399       2         0       ATT 6300
  66. 6Ah              799          599       16        0       VESA  (6)
  67. XMode16      up to 799     up to 599    16        0       Super EGA/VGA
  68. Super13          319          399       256       0, 1    VGA
  69. Super13a         359          479       256       0       VGA
  70. SVGA16      799 or 1023   599 or 767    16        0       Super VGA (7)
  71. SVGA256     639 to 1023   399 to 767    256       0       Super VGA (7)
  72.  
  73. (1) page numbering begins with page 0.  Several modes have sufficient
  74.     memory available for additional page(s).
  75. (2) page 1 available after calling Use64k
  76. (3) EGA pages assumes 256k EGA memory
  77. (4) monochrome monitor only
  78. (5) EGA with 128k or more memory
  79. (6) VESA6A is supported by many Super VGA cards with multi-frequency
  80.     monitors
  81. (7) requires VGAKIT-compatible Super VGA and multi-frequency monitor.  See
  82.     WhichVGA in SYSTEM.DOC and SVGA16 and SVGA256 in MODE.DOC.
  83.  
  84. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  85.  
  86. BITBLOCKBYTES: calculate bytes required to save a bit block
  87. Source:        bbbytes.asm ($graph.asm)
  88.  
  89. Call with:     DS:[BX] pointing to x- and y-coordinate data (see example)
  90. Returns:       DX:AX = bytes required to save the bit block
  91.                small or medium model:
  92.                   if CF = 0, bytes required is less than 64k segment
  93.                      => no problem
  94.                   if CF = 1, bit block is too big for a 64k segment
  95.                      small or medium model BitBlock subroutines will
  96.                      not work properly
  97. Uses:          AX, DX, flags
  98. Supports:      all ASMLIB graphics modes; call BitBlockBytes while
  99.                the system is in the mode you intend to use.  Otherwise,
  100.                an incorrect byte size may be returned, leading to either
  101.                wasted memory or memory allocation errors.
  102. Example:
  103.  
  104. include asm.inc
  105.  
  106. extrn   bitblockbytes:proc
  107.  
  108. .data
  109. x0      dw 100,43         ; first corner at (100,43)
  110. x1      dw 175,143        ; second corner at (175,143)
  111.  
  112. .code
  113. ; program fragment assumes DS:@data
  114.         .
  115.         .
  116.         .
  117.         lea    bx,x0          ; DS:[BX] points to bit block corner data
  118.         call   bitblockbytes  ; returns AX = byte size of buffer required
  119.         jc     too_big        ; bit block is too big if CF = 1 (small or med)
  120.  
  121. ; note that when the huge model is used, memory greater than 64k must be
  122. ; allocated with DOS function 48h.  See STARTUP.ASM to release unused
  123. ; memory to allow DOS memory allocation.
  124.  
  125.  
  126. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  127.  
  128. BITPLANEBYTES: calculate bytes to save one plane of a bit block
  129.                alternate entry to BitBlockBytes; calculates bytes
  130.                required to save one plane of multi-plane modes
  131. Source:        bbbytes.asm ($graph.asm)
  132. Call with:     DS:[BX] pointing to x- and y-coordinate data
  133. Returns:       DX:AX = bytes required to save the bit plane
  134.                small or medium model:
  135.                   if CF = 0, bytes required is less than 64k
  136.                      => no problem
  137.                   if CF = 1, bit plane is too big for a 64k segment
  138.                      small or medium model BitPlane subroutines will
  139.                      not work properly
  140. Uses:          AX, DX, flags
  141. Supports:      all ASMLIB graphics modes; call BitPlaneBytes while
  142.                the system is in the mode you intend to use.  If the
  143.                system is is not in a multi-plane mode, BitPlaneBytes
  144.                will give you the same results as BitBlockBytes.
  145.                Graphics modes with multiple planes are mode 0Fh (2 planes)
  146.                and all 16-color modes (4 planes).
  147. Example:
  148.  
  149. include asm.inc
  150.  
  151. extrn   bitplanebytes:proc
  152.  
  153. .data
  154. x0      dw 100,43         ; first corner at (100,43)
  155. x1      dw 175,143        ; second corner at (175,143)
  156.  
  157. .code
  158. ; program fragment assumes DS:@data
  159.         .
  160.         .
  161.         .
  162.         lea    bx,x0          ; DS:[BX] points to bit block corner data
  163.         call   bitplanebytes  ; returns AX = byte size of buffer required
  164.         jc     too_big        ; unlikely
  165.  
  166.  
  167. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  168.  
  169. CIRCLEASPECT:  modifies aspect ratio of circle
  170. Source:        drawcirc.asm ($graph.asm)
  171.  
  172. Call with:     AH = numerator of aspect ratio
  173.                AL = denominator of aspect ratio
  174.                AH <> 0, AL <> 0
  175.  
  176.                CircleAspect is used with DrawCircle to draw an ellipse.
  177.                An aspect ratio less than one makes a flat ellipse and an
  178.                aspect ratio greater than one makes a tall ellipse.
  179.                Aspect ratios greater than 5 or less than 1/5 may cause
  180.                unpredictable results.
  181.  
  182. Returns:       nothing
  183. Uses:          nothing; all registers and flags are saved
  184. Supports:      all ASMLIB graphics modes
  185. Example:       see DrawCircle
  186.  
  187.  
  188.  
  189. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  190.  
  191. DEFGMODE:      restore ASMLIB's internal flags to use system graphics
  192.                mode (see ForceGMode)
  193. Source:        defgmode.asm
  194.  
  195. Call with:     no parameters
  196. Returns:       nothing
  197. Uses:          nothing
  198. Supports:      all ASMLIB graphics modes
  199. Example:       see ForceGMode
  200.  
  201.  
  202.  
  203. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  204.  
  205. DRAWCIRCLE:    draw a circle
  206. Source:        drawcirc.asm ($graph.asm, $putdot.asm)
  207.  
  208. Call with:     DS:[BX] pointing to circle center coordinates and x-radius
  209.                Drawmodes supported are:
  210.                 4 = AND the foreground color with the screen
  211.                 3 = OR the foreground color with the screen
  212.                 1, 2 = use foreground color
  213.                 0 = XOR circle with existing screen
  214.                -1, -2 = use background color
  215.                -3 = OR the background color with the screen
  216.                -4 = AND the background color with the screen
  217.                See DrawMode for more information
  218.                See also CircleAspect
  219. Returns:       nothing
  220. Uses:          nothing
  221. Supports:      all ASMLIB graphics modes
  222. Example:
  223.  
  224. include asm.inc
  225. extrn   drawcircle:proc, circleaspect:proc
  226.  
  227. .data
  228. xcenter dw 100              ; DrawCircle data must be words
  229. ycenter dw 100              ; the circle is centered at (100,100)
  230. xradius dw 50               ; x-dimension radius in pixels (>0)
  231.  
  232. .code
  233. ; program fragment assumes DS:@data
  234.         .
  235.         .
  236.         .
  237.         mov   ah,5
  238.         mov   al,1          ; a tall ellipse
  239.         call  circleaspect
  240.  
  241.         lea   bx,xcenter    ; DS:[BX] points to circle data
  242.         call  drawcircle    ; draw the circle
  243.  
  244.  
  245. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  246.  
  247. DRAWBOX:       draw a rectangle on a graphics screen
  248. Source:        drawbox.asm ($graph.asm, $vert.asm, $horiz.asm, several others)
  249.  
  250. Call with:     DS:[BX] pointing to box corner data
  251.                Drawmodes supported are:
  252.                 4 = AND the foreground color with the screen; color modes
  253.                 3 = OR the foreground color with the screen
  254.                 1, 2 = use foreground color: all modes
  255.                 0 = XOR foreground color with existing pixels
  256.                -1, -2 = use background color: all modes
  257.                -3 = OR the background color with the screen
  258.                -4 = AND the background color with the screen; color modes
  259.                See DrawMode for more information; see also LinePattern
  260. Returns:       nothing
  261. Uses:          nothing
  262. Supports:      all ASMLIB graphics modes
  263. Example:
  264.  
  265. include asm.inc
  266.  
  267. extrn   drawbox:proc
  268.  
  269. .data
  270. x0      dw 25,10            ; first corner at (25,10); data is word size
  271. x1      dw 301,97           ; opposite corner at (301,97)
  272.  
  273. .code
  274. ; program fragment assumes DS:@data
  275.         .
  276.         .
  277.         lea   bx,x0         ; DS:[BX] points to box corner data
  278.         call  drawbox
  279.  
  280.  
  281. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  282.  
  283. DRAWLINE:      draw a line on a graphics screen
  284. Source:        drawline.asm ($graph.asm, $vert.asm, $horiz.asm,
  285.                              $loslope.asm, $hislope.asm, many others)
  286.  
  287. Call with:     DS:[BX] pointing to line endpoint data
  288.                Drawmodes supported are:
  289.                 4 = AND the foreground color with the screen; color modes
  290.                 3 = OR the foreground color with the screen
  291.                 1, 2 = use foreground color: all modes
  292.                 0 = XOR foreground color with existing pixels
  293.                -1, -2 = use background color: all modes
  294.                -3 = OR the background color with the screen
  295.                -4 = AND the background color with the screen; color modes
  296.                See DrawMode for more information; see also LinePattern
  297. Returns:       nothing
  298. Uses:          nothing
  299. Supports:      all ASMLIB graphics modes
  300. Example:
  301.  
  302. include asm.inc
  303.  
  304. extrn   drawline:proc
  305.  
  306. .data
  307. x0      dw 25,10            ; first endpoint at (25,10); data is word size
  308. x1      dw 301,97           ; other end of line at (301,97)
  309.  
  310. .code
  311. ; program fragment assumes DS:@data
  312.         .
  313.         .
  314.         lea   bx,x0         ; DS:[BX] points to line coordinate data
  315.         call  drawline
  316.  
  317.  
  318. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  319.  
  320. DRAWMODE:      control ASMLIB graphics drawing mode
  321. Source:        $graph.asm
  322.  
  323.                DrawMode is a public byte in DGROUP used to control the
  324.                operation of many ASMLIB subroutines.  ASMLIB's default
  325.                drawmode is 1.
  326.  
  327.                Typically, drawmodes have the following effects:
  328.                 2 = use foreground color only; text is printed without
  329.                     background, foreground only of line patterns or
  330.                     fill patterns is used
  331.                 1 = use foreground and background; text is printed with
  332.                     background, line patterns and fill patterns update
  333.                     both foreground and background
  334.                 0 = foreground color is XORed with the existing screen
  335.                     (not supported in 256-color or CGA 4-color modes)
  336.                -1 = characters or fill pattern drawn with foreground
  337.                     and background reversed
  338.                -2 = character or line drawn with background color only
  339.  
  340. Supports:      all ASMLIB graphics modes
  341. Example:
  342.  
  343. include asm.inc
  344.  
  345. .data
  346. extrn   drawmode:byte
  347.  
  348. .code
  349. ; program fragment assumes DS:@data
  350.         .
  351.         .
  352.         mov     drawmode,2      ; print text with foreground color only
  353.  
  354.  
  355. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  356.  
  357. FILLAREA:      fills an irregular area on a graphics screen
  358. Source:        fillarea.asm ($graph.asm, $horiz.asm, $getdot.asm,
  359.                              several others)
  360.  
  361. Call with:     DS:[BX] pointing to seed pixel coordinates
  362.  
  363.                Fills many irregularly-shaped areas with color and/or
  364.                pattern, beginning at (x,y).  FillArea may not work
  365.                properly with regions which have concave boundaries
  366.                crossing horizontal lines.  The area's boundary is
  367.                defined by a solid line of non-zero pixels.
  368.                DrawModes supported are:
  369.                 2 = fill with foreground color only (if fill pattern
  370.                     has been defined): 16-color modes
  371.                 1 = fill with foreground (and background, if fillpattern
  372.                     defined): all modes
  373.                See also FillPattern.
  374. Returns:       nothing
  375. Uses:          nothing
  376. Supports:      all ASMLIB graphics modes
  377. Example:
  378.  
  379. include asm.inc
  380.  
  381. extrn   fillarea:proc
  382.  
  383. .data
  384. x       dw 10,15         ; start fill operation at x=10, y=15
  385.  
  386. .code
  387. ; program fragment assumes DS:@data
  388.         .
  389.         .
  390.         lea    bx,x
  391.         call   fillpattern
  392.  
  393.  
  394. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  395.  
  396. FILLBOX:       draw a filled rectangle on a graphics screen
  397. Source:        fillbox.asm ($graph.asm, $horiz.asm, several others)
  398.  
  399. Call with:     DS:[BX] pointing to box corner data
  400.                Drawmodes supported are:
  401.                 4 = AND the box with the pre-existing screen
  402.                 3 = OR the foreground color with the screen
  403.                 1, 2 = use foreground color
  404.                 0 = XOR foreground color with existing pixels
  405.                -1, -2 = use background color
  406.                -3 = OR the background color with the screen
  407.                -4 = AND the background color with pre-existing screen
  408.                See DrawMode for more information; also see FillPattern.
  409. Returns:       nothing
  410. Uses:          nothing
  411. Supports:      all ASMLIB graphics modes
  412. Example:
  413.  
  414. include asm.inc
  415.  
  416. extrn   fillbox:proc
  417.  
  418. .data
  419. x0      dw 25,10            ; first corner at (25,10); data is word size
  420. x1      dw 301,97           ; opposite corner at (301,97)
  421.  
  422. .code
  423. ; program fragment assumes DS:@data
  424.         .
  425.         .
  426.         lea   bx,x0         ; DS:[BX] points to box corner data
  427.         call  fillbox
  428.  
  429.  
  430. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  431.  
  432. FILLPATTERN:   define an optional pattern for FillArea & FillBox
  433. Source:        fpattern.asm
  434.  
  435. Call with:     DS:[BX] pointing to ASCIIZ pattern string.
  436.                Up to 8 characters in the string will be used.
  437.                The pattern must be re-defined before each call to a line
  438.                drawing subroutine (FillArea, FillBox).
  439. Returns:       nothing
  440. Uses:          nothing
  441. Supports:      all ASMLIB graphics modes except 256-color modes
  442. Example:
  443.  
  444. include asm.inc
  445.  
  446. extrn   fillbox:proc
  447. extrn   fillpattern:proc
  448.  
  449. .data
  450. x0      dw 25,10            ; first corner at (25,10); data is word size
  451. x1      dw 301,97           ; opposite corner at (301,97)
  452. pattern db 8 dup(10101010b),0
  453.  
  454. .code
  455. ; program fragment assumes DS:@data
  456.         .
  457.         .
  458.         lea   bx,pattern    ; DS:[BX] points to pattern string
  459.         call  fillpattern   ; define the pattern
  460.         sub   bx,8          ; DS:[BX] points to box corner data
  461.         call  fillbox       ; draw a patterned box
  462.  
  463.  
  464. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  465.  
  466. FORCEGMODE:    force ASMLIB to use one particular graphics mode
  467.                this is handy for two-monitor systems
  468. Source:        defgmode.asm
  469.  
  470. Call with:     AL = graphics mode to use
  471.                forcegmode does not change the actual screen mode; what
  472.                it does is to force ASMLIB's central graphics control
  473.                to ignore the system mode.  Call defgmode to restore
  474.                ASMLIB's internal flags to the default state.
  475. Returns:       nothing
  476. Uses:          nothing
  477. Supports:      all ASMLIB graphics modes (256-color modes not tested)
  478. Example:
  479.  
  480. include asm.inc
  481.  
  482. extrn   modecolor:proc, modemono:proc
  483. extrn   forcegmode:proc, gcolor:proc, defgmode:proc
  484.  
  485. .data
  486. gtext   db 'Graphics mode',0
  487. gpos    dd 0                   ; 2 words of zeros to position text
  488. ttext   db 'Text mode',0
  489.  
  490. .code
  491. ; program fragment assumes DS:@data
  492. ; I want text on the monochrome screen and 16-color graphics on the EGA
  493.         call   modecolor       ; switch to color monitor
  494.         mov    ax,10h          ; set up graphics mode
  495.         int    10h
  496.         mov    al,10h          ; tell ASMLIB to use mode 10h
  497.                                ; use AL = 13h for VGA 256-color modes
  498.                                ; use AL = 8 for Hercules (including InColor)
  499.         call   forcegmode      ; best to do this after the mode change
  500.         call   modemono        ; switch back to the monochrome monitor
  501.         mov    ax,010Ch        ; blue background, red foreground
  502.         call   gcolor
  503.         lea    si,gtext        ; point to graphics message
  504.         lea    dx,gpos         ; positioned at upper left corner
  505.         call   gprint          ; prints on EGA in graphics mode
  506.  
  507.         lea    si,ttext        ; point to text message
  508.         xor    dx,dx           ; upper left corner of text screen
  509.         mov    ah,7            ; normal color
  510.         call   tprint          ; display message on monochrome monitor
  511.         .
  512.         .
  513. ; sometime later, all done with this setup
  514.         call   defgmode        ; clear ASMLIB's internal graphics flags
  515.  
  516.  
  517. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  518.  
  519. GBASESEG:      change ASMLIB graphics base segment
  520. Source:        gbaseseg.asm ($graph.asm)
  521.  
  522. Call with:     AX = base segment address for alternate buffer
  523.                if AX = 0, default base segment is restored
  524.                GBaseSeg may be used to create and update off-screen graph
  525.                images, thus simulating multiple screen pages.
  526. Returns:       nothing
  527. Uses:          nothing
  528. Supports:      mode 04h, 05h, HGraph (monochrome only), 40h, 11h, 13h
  529.  
  530.                buffer size requirements:
  531.  
  532.                 mode 04h, 05h    16384 bytes
  533.                 HGraph, 40h      32768 bytes
  534.                 mode 11h         38400 bytes
  535.                 mode 13h         64000 bytes
  536.  
  537.                 GBaseSeg may also work with planar or bank-switched
  538.                 modes in a windowing multi-tasking enviornment, such
  539.                 as DesqView.  Feedback, please!!
  540.                 You must call GBaseseg AFTER switching the system to graphics
  541.                 mode, or it will not work; you must also call GBaseSeg with
  542.                 AX = 0 before changing from one graphics mode to another, or
  543.                 the default base segment may get messed up.
  544. Example:
  545.  
  546. .model medium
  547.  
  548. public myprog
  549. extrn  gbaseseg:proc, drawbox:proc
  550.  
  551. .data
  552. boxdata dw 0,0,319,199
  553.  
  554. .fardata
  555. screen1 db 64000 dup (0)     ; second screen for mode 13h
  556.  
  557. .code
  558. myprog proc
  559. ; program fragment assumes DS:@DATA
  560. ; mode 13h, 320x200x256 colors
  561.        mov     ax,13h
  562.        int     10h
  563. ; use alternate buffer
  564.        mov     ax,seg screen1
  565.        call    gbaseseg
  566.        lea     bx,linedata
  567.        call    drawbox
  568.  
  569. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  570.  
  571. GCENTER:       centers a string on a graphics screen
  572. Source:        gcenter.asm (gprint.asm, $graph.asm, strlen.asm, f8x14.asm)
  573.  
  574. GCENTERX:      centers a double-width string on a graphics screen
  575. Source:        gcenterx.asm (gprintx.asm, $graph.asm, strlen.asm, f8x14.asm)
  576.  
  577. Call with:     DS:[SI] pointing to the string to print
  578.                DS:[DX] pointing to x- and y-coordinates
  579.                the x-coordinate is a placeholder; GCenter calculates the
  580.                correct x value before calling GPrint.
  581.  
  582.                Colors, drawmodes and character sizes are the same as
  583.                for GPrint or GPrintX.
  584. Returns:       x = calculated x-coordinate
  585. Uses:          nothing; all registers and flags are saved.
  586. Supports:      all ASMLIB graphics modes
  587. Example:
  588.  
  589. include asm.inc
  590.  
  591. extrn   gcenter:proc
  592.  
  593. .data
  594. x       dw ?
  595. y       dw 2               ; print graph title 2 pixels down from the top
  596. title   db 'Graph title',0
  597.  
  598. .code
  599. ; program fragment assumes DS:@data
  600.         .
  601.         .
  602.         lea    si,title    ; DS:[SI] points to string
  603.         lea    dx,x        ; point to coordinates
  604.         call   gcenter     ; print the string, centered horizontally
  605.  
  606.  
  607. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  608.  
  609. GCLEAR:        clears the active portion of a graphics screen
  610.                uses background color
  611. Source:        gclear.asm ($graph.asm, $horiz.asm, others)
  612.  
  613. Call with:     no parameters
  614. Returns:       nothing
  615. Uses:          nothing
  616. Supports:      all ASMLIB graphics modes
  617. Example:
  618.  
  619. include asm.inc
  620.  
  621. extrn   gclear:proc
  622.  
  623. .code
  624.         .
  625.         .
  626.         .
  627.         call  gclear
  628.  
  629. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  630.  
  631. GCOLOR:        update color used by ASMLIB graphics
  632. Source:        gcolor.asm ($graph.asm)
  633.  
  634. Call with:     AL = foreground color
  635.                AH = background color
  636.  
  637.                for 4-color modes, colors may be 0-3
  638.                for 16-color modes, colors may be 0-15
  639.                for 256-color modes, colors may be 0-255
  640.  
  641. Returns:       nothing
  642. Uses:          nothing
  643. Supports:      all color graphics modes and mode 0Fh
  644.                GColor is ignored by 2-color modes
  645. Example:
  646.  
  647. include asm.inc
  648.  
  649. extrn   gcolor:proc
  650.  
  651. .code
  652.         .
  653.         .
  654.         .
  655.         mov   ah,bcolor      ; background color
  656.         mov   al,fcolor      ; foreground color
  657.         call  gcolor
  658.  
  659.  
  660. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  661.  
  662. GCOPY:         copies one page of graphics memory to another
  663. Source:        gcopy.asm ($graph.asm)
  664.  
  665. Call with:     BH = frompage
  666.                BL = topage
  667. Returns:       CF = error flag
  668.                 if CF = 0, no error
  669.                 if CF = 1, bad page number or frompage = topage
  670. Uses:          AX, CF
  671. Supports:      Hercules and InColor (with Use64k)
  672.                EGA/VGA modes 0Dh, 0Eh, 0Fh, 10h
  673.                Super13
  674. Example:
  675.  
  676. include asm.inc
  677.  
  678. extrn   gcopy:proc
  679.  
  680. .code
  681.         .
  682.         .
  683.         .
  684.         mov   bx,0001h       ; copy from page 0 to page 1
  685.         call  gcopy
  686.         jc    bad_page       ; uh oh, pages not supported
  687.  
  688.  
  689. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  690.  
  691. GCURSOR:       simulate text-mode cursor on graphics screen
  692. GUCURSOR:      simulate underscore cursor on graphics screen
  693. Source:        gcursor.asm ($graph.asm)
  694.  
  695. Call with:     DS:[DX] pointing to x- and y-coordinate word data
  696.                x and y are the coordinates of the UPPER LEFT corner of
  697.                a character block.  Note that text characters are
  698.                8 x-pixels wide and from 8 to 16 y-pixels high.
  699.  
  700.                GCursor and GUCursor maintain the simulated cursor while
  701.                the keyboard type-ahead buffer is empty.  GCursor shape
  702.                is an underscore when INSERT is off and a larger block
  703.                when INSERT is on.  GUCursor is an underscore regardless
  704.                of the state of the INSERT toggle.
  705. Returns:       nothing
  706. Uses:          AX, CX
  707. Supports:      all ASMLIB graphics modes
  708. Example:
  709.  
  710. include asm.inc
  711.  
  712. extrn   gcursor:proc, getkey:proc
  713.  
  714. .data
  715. x       dw 10,20        ; put the cursor in the character block at (10,20)
  716.  
  717. .code
  718. ; program fragment assumes DS:@data
  719.         .
  720.         .
  721.         .
  722.         lea   dx,x
  723.         call  gcursor
  724.         call  getkey    ; retrieve the key that was pressed
  725.  
  726.  
  727. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  728.  
  729. GETBITBLOCK:   saves a portion of a graphics screen in memory
  730. Source:        small & medium: bitblock.asm ($graph.asm, bb02.asm, bb04.asm
  731.                                bb06.asm, bb08.asm, bb10.asm, bb12.asm,
  732.                                bb14.asm)
  733.                huge: same as small & medium, + lowES2hi.asm & lowDS2hi.asm
  734.  
  735. Call with:     ES:[DI] pointing to memory buffer for the bit block
  736.                DS:[BX] pointing to x & y coordinate data
  737.  
  738.                Note that a bit block copied from a 4-plane mode may
  739.                only be restored to a 4-plane mode; likewise, a bit
  740.                block saved from a 2-color mode should be restored to
  741.                a 2-color mode or to a single bit plane of a 16-color
  742.                mode.
  743. Returns:       nothing
  744. Uses:          nothing
  745. Supports:      all ASMLIB graphics modes
  746.                memory models: small medium, huge
  747.  
  748.  
  749.     If you do not intend to support all ASMLIB graphics modes, you can
  750.     call mode-specific BitBlock subroutines to reduce .EXE size.
  751.     These subroutines use the same calling parameters as GetBitBlock
  752.     and PutBitBlock:
  753.  
  754.  
  755.     getbb02: mode 04h, 05h, 11h, 40h, HGraph (mono and InColor)
  756.     getbb06: mode 0Dh, 0Eh, 0Fh, 10h, 12h, SVGA16(0), XMODE16
  757.     getbb08: mode 13h
  758.     getbb10: Super13, Super13a
  759.     getbb12: SVGA16
  760.     getbb14: SVGA256
  761.  
  762.  
  763.     putbb02: mode 04h, 05h, 11h, 40h, HGraph (mono only)
  764.     putbb04: HGraph (InColor only)
  765.     putbb06: mode 0Dh, 0Eh, 0Fh, 10h, 12h, SVGA16(0), XMODE16
  766.     putbb08: mode 13h
  767.     putbb10: Super13, Super13a
  768.     putbb12: SVGA16
  769.     putbb14: SVGA256
  770.  
  771. Example on next page
  772.  
  773.  
  774. ; example of GetBitBlock use
  775.  
  776. include asm.inc
  777.  
  778. extrn   bitblockbytes:proc, getbitblock:proc, putbitblock:proc
  779. extrn   halloc:proc
  780.  
  781. .data
  782. ptr     dw ?                ; use this to save pointer to bit block
  783. x0      dw 100,43,175,143   ; save from (100,43) to (175,143)
  784.  
  785. .code
  786. ; program fragment assumes DS:@data
  787.         .
  788.         .
  789.         lea   bx,x0         ; point to block corners
  790.         call  bitblockbytes ; calculate byte requirement
  791.         jc    too_big       ; error control
  792.         call  halloc        ; this example allocate the buffer from heap
  793.                             ; can't do this w/ huge bit blocks
  794.         jc    no_memory     ; more error control
  795.         mov   ptr,bx        ; save near address of bit block
  796.         push  ds
  797.         pop   es            ; ES = DS
  798.         mov   di,bx         ; ES:[DI] points to buffer
  799.         lea   bx,x0         ; DS:[BX] points to coordinate data
  800.         call  getbitblock
  801.         .
  802.         .
  803.  
  804. ; later . . .
  805.         lea   bx,x0         ; put the bit block back where you found it
  806.         push  ds
  807.         pop   es            ; ES = DS
  808.         mov   di,ptr        ; ES:[DI] points to buffer
  809.         call  putbitblock
  810.  
  811. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  812.  
  813. GETBITPLANE:   saves one plane of a bit block in memory
  814. Source:        small & medium: bitplane.asm ($graph.asm, bb02.asm, bb04.asm
  815.                                bb06.asm, bb08.asm, bb10.asm, bb12.asm,
  816.                                bb14.asm)
  817.                huge: same as small & medium, + lowES2hi.asm & lowDS2hi.asm
  818.  
  819. Call with:     ES:[DI] pointing to memory buffer for the bit block
  820.                DS:[BX] pointing to x & y coordinate data
  821.                AL = plane number to save
  822.                valid plane numbers are 0 - 3 in 16-color modes
  823.                                        0 & 2 in EGA monochrome mode
  824.  
  825.                In 16-color modes, EGA/VGA and InColor planes are:
  826.                 0 = blue, 1 = green, 2 = red, 3 = gray (or intensity)
  827.                In EGA monochrome mode, plane 0 = normal, plane 2 = blink
  828.                 or intensity
  829.                The actual colors each plane represents may change
  830.                depending on the values in the pallete registers.
  831.  
  832. Supports:      all 16-color modes plus EGA monochrome
  833.                other modes: GetBitPlane works like GetBitBlock
  834.                memory models: small, medium, huge
  835.  
  836.  
  837. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  838.  
  839. GETVIEW:       returns a pointer to the current view coordinates for
  840.                the active page
  841. Source:        getview.asm ($graph.asm)
  842.  
  843. Call with:     no parameters
  844.                most ASMLIB subroutines, except the GPrint series, Gload,
  845.                GCopy and GSave, limit their activity to the view region.
  846.                You may use the returned pointer to change the active
  847.                portion of the screen; be careful not to exceed the maximum
  848.                x1 and y1 values permitted by the current mode.  Also, x0
  849.                must always be less than x1 and y0 must always be less than
  850.                y1.
  851.                ASMLIB's defaults are:
  852.                 x0 = 0
  853.                 y0 = 0
  854.                 x1 = xmax
  855.                 y1 = ymax
  856.  
  857.                See also ResetView
  858.  
  859. Returns:       ES:[BX] pointing to the current view coordinates
  860. Uses:          ES, BX; all other registers and flags are saved
  861. Supports:      all ASMLIB graphics modes and pages
  862. Example:
  863.  
  864. include asm.inc
  865.  
  866. extrn   getview:proc
  867.  
  868. x0 EQU word ptr ES:[BX]
  869. y0 EQU word ptr ES:2[BX]
  870. x1 EQU word ptr ES:4[BX]
  871. y1 EQU word ptr ES:6[BX]
  872.  
  873. .code
  874.         .
  875.         .
  876.         .
  877.         call   getview
  878.  
  879.  
  880. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  881.  
  882. GLOAD:         loads a graphics screen saved as a disk file by GSave
  883. Source:        gsave.asm ($graph.asm, $gbytes.asm, $reset.asm)
  884.  
  885. Call with:     DS:[DX] pointing to the name of the file to load
  886.                the filename must be an ASCIIZ string
  887. Returns:       AX = MS-DOS error code
  888. Uses:          AX, BX, CX, flags
  889. Supports:      all ASMLIB graphics modes
  890. Example:
  891.  
  892. include asm.inc
  893.  
  894. extrn   gload:proc
  895.  
  896. .data
  897. filename db 'graph.bin',0
  898.  
  899. .code
  900. ; program fragment assumes DS:@data
  901.         .
  902.         .
  903.         lea   dx,filename
  904.         call  gload
  905.  
  906.  
  907. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  908.  
  909. GPAGE:         changes active and displayed graphics page
  910.                GPage changes ASMLIB's default graphics page and displays
  911.                the page.  See also UseGPage and ShowGPage.
  912. Source:        gpage1.asm ($graph.asm, $herc.asm, gpage.asm)
  913.  
  914. Call with:     BL = page number.  See table at start of this GRAPHICS.DOC
  915.                file.
  916. Returns:       if CF = 0, no problem
  917.                if CF = 1, bad page number requested
  918. Uses:          CF
  919. Supports:      EGA, VGA, Hercules, InColor: modes with more than one page
  920. Example:
  921.  
  922. include asm.inc
  923.  
  924. extrn   gpage:proc
  925.  
  926. .code
  927.         .
  928.         .
  929.         mov    bl,1          ; use and show page 1
  930.         call   gpage
  931.         jc     oops          ; uh oh, wrong mode
  932.  
  933. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  934.  
  935. GPRINT:        prints ASCIIZ string on a graphics screen
  936. Source:        gprint.asm ($graph.asm, f8x14.asm, $gp00.asm, $gp02.asm,
  937.                            $gp06.asm, $gp08.asm, $gp10.asm, others)
  938.  
  939. Call with:     DS:[SI] pointing to the ASCIIZ string
  940.                DS:[DX] pointing to x- and y-coordinate data
  941.                drawmodes supported by GPrint are:
  942.                 2 = foreground only; background pixels left alone
  943.                 1 = foreground and background pixels updated with
  944.                     current gcolor
  945.                 0 = foreground color is XORed with the existing screen
  946.                -1 = like drawmode 1, but foreground and background reversed
  947.                -2 = like drawmode 2, but uses background color
  948.                Any pixel position may be specified; does not wrap around
  949.                from right side of screen to left.  Default character size
  950.                is 8x8 for CGA modes and modes 0Dh, 0Eh and 13h, 8x14 for
  951.                others.
  952.                High ASCII characters are undefined in 8x8 pixel modes
  953.                unless you call SmallText sometime earlier in the program.
  954. Returns:       nothing
  955. Uses:          CX; all other registers and flags are saved
  956. Supports:      all ASMLIB graphics modes
  957.                not all drawmodes supported with CGA modes 04h and 05h
  958. Example:
  959.  
  960. include asm.inc
  961.  
  962. extrn   gprint:proc
  963.  
  964. .data
  965. string  db 'print this, if you will',0
  966. gpos    dw 0,0                          ; print at upper left corner
  967.  
  968. .code
  969. ; program fragment assumes DS:@data
  970.         .
  971.         .
  972.         .
  973.         lea   si,string
  974.         lea   dx,gpos
  975.         call  gprint
  976.  
  977. additional GPRINT information on next page
  978.  
  979. GPRINT will work with user-defined fonts up to 16 pixel rows high in all
  980. modes with ymax > 200.  GPRINT reads a public data area in DGROUP to
  981. determine the SEGMENT:OFFSET address of the font data, the number of pixel
  982. rows per character and the byte increment between sucessive character
  983. definitions.  Characters must be 8 pixels wide.
  984.  
  985. FONTDATA.ASM has the required font data:
  986.  
  987. public  fontseg
  988. fontseg dw SEG f8x14    ; segment address of user-loaded font (8x14 default)
  989.         dw OFFSET f8x14 ; offset address of user-loaded font (8x14 default)
  990.         db 14           ; byte size of character
  991.         db 14           ; bytes from start of one char to start of next
  992.  
  993. Example:
  994.  
  995. include asm.inc
  996.  
  997. .data
  998. extrn   fontseg:word
  999.  
  1000. fname   db 'c:\ramfont\italics.fnt',0   ; 8x14 characters
  1001. fbuffer db 4096 dup (0)                 ; all RAMFont fonts are 4096 bytes
  1002. ; the fonts supplied by Hercules with the Graphics Card Plus and InColor
  1003. ; card are a variety of sizes, but in each font file the byte increment
  1004. ; is always 16 bytes
  1005.  
  1006. .code
  1007.         .
  1008.         .
  1009.         mov     ax,@data
  1010.         mov     ds,ax
  1011.         lea     dx,fname
  1012.         mov     ax,3D00h        ; open file for read
  1013.         int     21h
  1014.         mov     bx,ax           ; copy file handle to BX
  1015.         lea     dx,fbuffer      ; DS:[DX] points to buffer
  1016.         mov     cx,4096
  1017.         mov     ah,3Fh          ; read file
  1018.         int     21h
  1019.         mov     ah,3Eh          ; close file
  1020.         int     21h
  1021.         mov     fontseg,ds      ; update segment address of new font
  1022.         mov     fontseg+2,dx    ; update offset address of new font
  1023.         mov     fontseg+4,(16 shl 8) OR 14
  1024.                                 ; 14-pixel row character
  1025.                                 ; 16 bytes between character definitions
  1026.  
  1027. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1028.  
  1029. GPRINTDOWN:    prints ASCIIZ string vertically on graph screen
  1030. GPRINTUP:      prints ASCIIZ string vertically on graph screen
  1031. Source:        gprint.asm ($graph.asm, f8x14.asm, $gp00.asm, $gp02.asm,
  1032.                            $gp06.asm, $gp08.asm, $gp10.asm, others)
  1033.  
  1034. Call with:     same as GPrint
  1035.                rotates each character 90 degrees and prints from top
  1036.                downward or from bottom upward.  Character size 8x8.
  1037.  
  1038.                Returned data and registers used same as GPrint
  1039. Example:       see GPrint.
  1040.  
  1041.  
  1042. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1043.  
  1044. GPRINTX:       print string on a graphics screen, double width
  1045. GPRINT2X:      print string on a graphics screen, double size
  1046. GPRINTDOWNX:   print string vertically on graph screen, 2x width
  1047. GPRINTDOWN2X:  print string vertically on graph screen, 2x size
  1048. GPRINTUPX:     print string vertically on graph screen, 2x width
  1049. GPRINTUP2X:    print string vertically on graph screen, 2x size
  1050. Source:        gprintx.asm ($graph.asm, f8x14.asm, $gp00.asm, $gp02.asm,
  1051.                             $gp06.asm, $gp08.asm, $gp10.asm, others)
  1052.  
  1053.  
  1054.                Variations of GPrint and GPrintDOWN/GPrintUP;
  1055.                GPrintx, GPrintDOWNx and GPrintUPx print characters
  1056.                which are twice as wide as normal; 2x subroutines
  1057.                print the characters twice as wide and twice as high
  1058.                as normal.
  1059.  
  1060.                Parameters, supported modes and drawmodes are same as
  1061.                GPrint.  GPrintx and GPrint2x also work with user-defined
  1062.                fonts.  See GPrint.
  1063. Example:       see GPrint.
  1064.  
  1065.  
  1066. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1067.  
  1068. GSAVE:         saves a graphics screen as a disk file
  1069.                does not compress image
  1070. Source:        gsave.asm ($graph.asm, $gbytes.asm, $reset.asm)
  1071.  
  1072. Call with:     DS:[DX] pointing to ASCIIZ filename
  1073.                disk space requirements vary depending on graphics mode:
  1074.  
  1075.                  HGraph  (mono)       32,768 bytes
  1076.                  HGraph  (InColor)   131,072 bytes
  1077.                  Super13             128,000 bytes
  1078.                  Super13a            172,800 bytes
  1079.                  XMode16  varies; up to 240,000 bytes
  1080.                  VESA6Ah, SVGA16(0)  240,000 bytes
  1081.                  SVGA16(1)           393,216 bytes
  1082.                  SVGA256(0)          256,000 bytes
  1083.                  SVGA256(1)          307,200 bytes
  1084.                  SVGA256(2)          480,000 bytes
  1085.                  SVGA256(3)          786,432 bytes
  1086.                  04h/05h/06h          16,384 bytes
  1087.                  40h                  32,768 bytes
  1088.                  0Dh                  32,000 bytes
  1089.                  0Eh                  64,000 bytes
  1090.                  0Fh                  56,000 bytes
  1091.                  10h                 112,000 bytes
  1092.                  11h                  38,400 bytes
  1093.                  12h                 153,600 bytes
  1094.                  13h                  64,000 bytes
  1095.  
  1096. Returns:       if AX <> 0, AX = MS-DOS error code
  1097.                if AX = 0, no error
  1098. Uses:          AX, flags
  1099. Supports:      all ASMLIB graphics modes
  1100. Example:
  1101.  
  1102. include asm.inc
  1103.  
  1104. extrn   gsave:proc
  1105.  
  1106. .data
  1107. filename db 'graph.bin',0
  1108.  
  1109. .code
  1110. ; program fragment assumes DS:@data
  1111.         .
  1112.         .
  1113.         .
  1114.         lea   dx,filename         ; point to ASCIIZ filename
  1115.         call  gsave               ; save graph
  1116.         or    ax,ax               ; was there a problem?
  1117.         jnz   oops                ; do some error control if so
  1118.  
  1119.  
  1120. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1121.  
  1122. LINEPATTERN:   defines an optional pattern for DrawLine and DrawBox
  1123. Source:        lpattern.asm ($graph.asm)
  1124.  
  1125. Call with:     DS:[BX] pointing to an ASCIIZ string of up to 8 characters.
  1126.                The bit patterns in each character are used to make dashed
  1127.                or dotted lines. For drawmodes > 0, each pixel in the line
  1128.                is updated with the foreground color if the corresponding
  1129.                bit in the bit pattern is 1.  If the bit in the bit pattern
  1130.                is 0, the corresponding pixel in the line is treated as a
  1131.                background pixel.  LinePattern must be called before each
  1132.                call to a subroutine in drawline.obj if you want the line
  1133.                pattern to be used.
  1134.  
  1135.                drawmodes supported are:
  1136.                (monochrome modes)
  1137.                 2 = update foreground pixels only
  1138.                 1 = update foreground and background pixels
  1139.                 0 = XOR the foreground color with the existing image
  1140.                -1 = like drawmode 1, but foreground and background colors
  1141.                     are reversed
  1142.                -2 = like drawmode 2, but foreground and background colors
  1143.                     are reversed
  1144.                (color modes)
  1145.                same as monochrome, plus:
  1146.                 3 = OR the foreground pixels with the pre-existing screen
  1147.                -3 = OR the background pixels with the pre-existing screen
  1148.                 4 = AND the foreground pixels with the pre-existing screen
  1149.                -4 = AND the background pixels with the pre-existing screen
  1150.  
  1151. Returns:       nothing
  1152. Uses:          nothing
  1153. Supports:      all ASMLIB graphics modes
  1154. Example:
  1155.  
  1156. include asm.inc
  1157.  
  1158. extrn   linepattern:proc, drawline:proc
  1159.  
  1160. .data
  1161. x0      dw 25,10,301,97          ; line endpoints at (25,10) & (301,97)
  1162. pattern db 4 dup(32,64),0        ; 8 bytes past x0
  1163.  
  1164. .code
  1165. ; program fragment assumes DS:@data
  1166.         .
  1167.         .
  1168.         lea   bx,pattern         ; DS:[BX] points to bit pattern
  1169.         call  linepattern        ; let drawline know what pattern to use
  1170.         sub   bx,8               ; point to line endpoint data
  1171.         call  drawline           ; draw a patterned line
  1172.  
  1173. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1174.  
  1175. PUTBITBLOCK:   restores bit block saved by GetBitBlock
  1176. PUTBITPLANE:   restores bit plane saved by GetBitPlane
  1177. Source:        same as GetBitBlock or GetBitPlane
  1178.  
  1179. Call with:     DS:[BX] pointing to upper left corner coordinates
  1180.                ES:[DI] pointing to buffer with stored bit block
  1181.                 PutBitPlane: AL = plane number
  1182.                 valid plane numbers for 16-color modes are 0 - 3
  1183.                                     for EGA mode 11h       0 & 2
  1184.  
  1185.                Drawmodes supported are:
  1186.                 mode 13h, super13, super13a:
  1187.                  1 = replace existing screen area with bit block
  1188.                  2 = replace existing screen with non-zero pixels
  1189.                      in bit block
  1190.  
  1191.                 HGraph (InColor):
  1192.                  4 = AND the bit block with the existing screen
  1193.                  3 = OR the bit block with the existing screen
  1194.                  1,2 = replace existing screen area with bit block
  1195.                  0 = XOR the bit block with the existing image
  1196.                 -1,-2 = replace existing screen area with inverse bit block
  1197.  
  1198.                 16-color EGA/VGA-type modes and mode 0Fh:
  1199.                  same as InColor, plus:
  1200.                 -3 = OR the inverse bit block with the existing screen
  1201.                 -4 = AND the inverse bit block with the existing screen
  1202.  
  1203.                 mode 04h, 05h, 06h, 40h, HGraph (mono), 11h:
  1204.                  4, 1, 0, -1 same as InColor
  1205.                  2, 3 = combine non-zero pixels in the bit block with the
  1206.                         pre-existing image
  1207.                 -2 = combine non-zero pixel in the inverse bit block with
  1208.                      the pre-existing screen image
  1209.  
  1210. Returns:       nothing
  1211. Uses:          nothing
  1212. Supports:      all ASMLIB graphics modes
  1213. Example:       see GetBitBlock
  1214.  
  1215.  
  1216. bit block formats explained on following pages
  1217.  
  1218.  
  1219. ; BIT BLOCK FORMATS
  1220.  
  1221. ; mode 04h, 05h, 06h Hercules monochrome, 11h, and bit planes
  1222. ;
  1223. ; the first word in the buffer is the number of pixel rows (vertical)
  1224. ; in the bit block; the second word is the number of bytes per screen row;
  1225. ; the fifth byte is a bit mask for the last byte of each pixel row.
  1226. ; The bit mask = 0FFh for byte-aligned bit blocks.
  1227.  
  1228. bblock  dw 15,5              ; 15 rows, 5 bytes per row
  1229.         db 11111110b         ; bit mask for right end of pixel row
  1230.                              ; bit block data follows:
  1231.                              ;  15 rows, 5 bytes per row
  1232.         db 00000000b,10000000b,00000000b,10000000b,00000010b
  1233.         db 00000001b,11000000b,00000001b,11000000b,00000110b
  1234.         db 00000011b,11100000b,00000011b,11100000b,00001100b
  1235.         db 00000111b,01110000b,00000111b,01110000b,00011000b
  1236.         db 00001110b,00111000b,00001110b,00111000b,00110000b
  1237.         db 00011100b,00011100b,00011100b,00011100b,01100000b
  1238.         db 00000001b,11000000b,00000001b,11000000b,11000000b
  1239.         db 00000001b,11000000b,00000001b,11000000b,01100000b
  1240.         db 00000001b,11000000b,00000001b,11000000b,00110000b
  1241.         db 00000001b,11000000b,00000001b,11000000b,00011000b
  1242.         db 00000001b,11000000b,00000001b,11000000b,00001100b
  1243.         db 00000001b,11000000b,00000001b,11000000b,00000110b
  1244.         db 00000001b,11000000b,00000001b,11000000b,00000010b
  1245.         db 00000001b,11000000b,00000001b,11000000b,00000000b
  1246.         db 00000001b,11000000b,00000001b,11000000b,00000000b
  1247.  
  1248. ; 16-color modes: 0Dh, 0Eh, 10h, 12h, 6Ah, xmode16, InColor:
  1249. ; same as above, except there are 4 planes of bit block data
  1250. ; i. e., 4 groups of 15-row, 5-byte data; plane 3 is the first
  1251. ; block, followed by planes 2, 1, and 0.
  1252.  
  1253. ; EGA monochrome mode: 0Fh
  1254. ; similar to 16-color modes, but there are only 2 groups of bit
  1255. ; block data instead of 4
  1256.  
  1257.  
  1258. ; 256-color modes on next page
  1259.  
  1260.  
  1261. ; BIT BLOCK FORMATS
  1262.  
  1263. ; mode 13h: no bit mask in the bit block header
  1264.  
  1265. red     equ 12                    ; bright red
  1266. blue    equ 1                     ; blue
  1267.  
  1268. bblock  dw 12,5                   ; 12 rows, 5 bytes per row
  1269.         db red, red, blue,red, red
  1270.         db red, blue,red, blue,red
  1271.         db blue,red, red, red, blue
  1272.         db red, red, blue,red, red
  1273.         db red, blue,red, blue,red
  1274.         db blue,red, red, red, blue
  1275.         db red, red, blue,red, red
  1276.         db red, blue,red, blue,red
  1277.         db blue,red, red, red, blue
  1278.         db red, red, blue,red, red
  1279.         db red, blue,red, blue,red
  1280.         db blue,red, red, red, blue
  1281.  
  1282. ; super13, super13a: no bit mask in the bit block header, x & y
  1283. ; orienation of data is reversed for speed
  1284. ; this example is the same pattern shown for mode 13h, above
  1285.  
  1286. red     equ 12                    ; bright red
  1287. blue    equ 1                     ; blue
  1288.  
  1289. bblock  dw 12,5                   ; 12 rows, 5 bytes per row
  1290.         db red, red, blue,red, red, blue,red, red, blue,red, red, blue
  1291.         db red, blue,red, red, blue,red, red, blue,red, red, blue,red
  1292.         db blue,red, red, blue,red, red, blue,red, red, blue,red, red
  1293.         db red, blue,red, red, blue,red, red, blue,red, red, blue,red
  1294.         db red, red, blue,red, red, blue,red, red, blue,red, red, blue
  1295.  
  1296.  
  1297. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1298.  
  1299. PUTDOT:        change a pixel on a graphics screen
  1300. Source:        putdot.asm ($graph.asm, $putdot.asm, others)
  1301.  
  1302. Call with:     DS:[BX] pointing to x & y coordinates
  1303.                Drawmodes supported are:
  1304.                (monochrome)
  1305.                 1 = set pixel
  1306.                 0 = toggle pixel
  1307.                -1 = erase pixel
  1308.  
  1309.                (color modes)
  1310.                 3 = OR foreground color with pre-existing pixel
  1311.                 1, 2 = replace pixel with foreground color
  1312.                 0 = XOR foreground color with pre-existing pixel
  1313.                -1, -2 = replace pixel with background color
  1314.                -3 = OR background color with pre-existing pixel
  1315. Returns:       if CF = 0, no error
  1316.                if CF = 1, pixel coordinates outside active view area
  1317. Uses:          CF; all other registers and flags are saved
  1318. Supports:      all ASMLIB graphics modes
  1319. Example:
  1320.  
  1321. include asm.inc
  1322.  
  1323. extrn   putdot:proc
  1324.  
  1325. .data
  1326. extrn   drawmode:byte
  1327. x       dw 100,117            ; pixel at x = 100, y = 117
  1328.  
  1329. .code
  1330. ; program fragment assumes DS:@data
  1331.         .
  1332.         .
  1333.         .
  1334.         mov   drawmode,1      ; use foreground color
  1335.         lea   bx,x            ; point to pixel coordinates
  1336.         call  putdot
  1337.  
  1338.  
  1339.  
  1340. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1341.  
  1342. GETDOT:        determine pixel value on graphics screen
  1343. Source:        getdot.asm ($graph.asm, $getdot.asm, others)
  1344.  
  1345. Call with:     DS:[BX] pointing to pixel coordinate data
  1346. Returns:       if CF = 0, AX = pixel value
  1347.                if CF = 1, pixel coordinates outside active view area
  1348. Uses:          AX, CF
  1349. Supports:      all ASMLIB graphics modes
  1350. Example:
  1351.  
  1352. include asm.inc
  1353.  
  1354. extrn   getdot:proc
  1355.  
  1356. .data
  1357. x       dw 10,10             ; pixel at (10,10)
  1358.  
  1359. .code
  1360. ; program fragment assumes DS:@data
  1361.         .
  1362.         .
  1363.         .
  1364.         lea    bx,x          ; point to pixel coordinates
  1365.         call   getdot        ; get pixel value
  1366.         jc     out_of_bounds ; oops
  1367.  
  1368.  
  1369.  
  1370. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1371.  
  1372. RESETVIEW:     restores default view area on active graphics page and
  1373.                returns a pointer to the view data
  1374. Source:        view.asm ($graph.asm)
  1375.  
  1376. Call with:     no parameters
  1377.                ResetView restores the default full screen view area.
  1378.                The far pointer returned points to ASMLIB's data area in
  1379.                $graph.obj for the active graphics page's view coordinates.
  1380. Returns:       ES:[BX] pointing to the active page's view data.
  1381. Uses:          ES, BX; all other registers and flags are saved
  1382. Supports:      all ASMLIB graphics modes
  1383. Example:
  1384.  
  1385. include asm.inc
  1386.  
  1387. extrn   resetview:proc
  1388.  
  1389. x0 EQU word ptr ES:[BX]
  1390. y0 EQU word ptr ES:2[BX]
  1391. x1 EQU word ptr ES:4[BX]
  1392. y1 EQU word ptr ES:6[BX]
  1393.  
  1394. .code
  1395.         .
  1396.         .
  1397.         .
  1398.         call  resetview
  1399.  
  1400.  
  1401.  
  1402. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1403.  
  1404. SHOWGPAGE:     change graphics page displayed on screen
  1405.                See also UseGPage and GPage.
  1406. Source:        gpage1.asm ($graph.asm, $herc.asm)
  1407.  
  1408. Call with:     BL = page number
  1409. Returns:       Carry Flag = error code
  1410.                if CF = 0, no error
  1411.                if CF = 1, bad page number
  1412. Uses:          CF
  1413. Supports:      HGraph (mono and InColor), modes 0Dh, 0Eh, 0Fh, 10h, Super13
  1414. Example:
  1415.  
  1416. include asm.inc
  1417.  
  1418. extrn   showgpage:proc
  1419.  
  1420. .code
  1421.         .
  1422.         .
  1423.         .
  1424.         mov   bl,1           ; show page 1
  1425.         call  showgpage
  1426.         jc    no_page_1      ; no page 1 for this mode
  1427.  
  1428. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1429.  
  1430. SHOWGPLANE:    show one or more planes of multi-plane EGA/VGA screen
  1431. Source:        gplane.asm ($graph.asm)
  1432.  
  1433. Call with:     AL = plane mask
  1434.                Bits set in the plane mask correspond to the plane displayed.
  1435.                ASMLIB's default mask is 00001111b, enabling all 4 planes.
  1436. Returns:       CF = error flag
  1437.                if CF = 0, no error
  1438.                if CF = 1, bad plane mask or graphics mode
  1439. Uses:          CF
  1440. Supports:      EGA & VGA 16-color modes, including VESA 6Ah, xmode16
  1441.                    and SVGA16
  1442.                EGA monochrome: planes 0 and 2
  1443.                    (mask = 00000101b for both planes)
  1444.                Hercules InColor
  1445. Example:
  1446.  
  1447. include asm.inc
  1448.  
  1449. extrn   showgplane:proc
  1450.  
  1451. .code
  1452.         .
  1453.         .
  1454.         .
  1455.         mov   al,00000101b      ; show planes 0 and 2
  1456.         call  showgplane
  1457.         jc    error             ; error control
  1458.  
  1459.  
  1460.  
  1461. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1462.  
  1463. SMALLTEXT:     change GPrint, GPrintX and GPrint2X default to 8x8 characters
  1464.                in Hercules and modes 10h, 11h, 12h; makes 8x8-size
  1465.                high ASCII characters available to GPrint in all modes
  1466. STDTEXT:       restore GPrint default characters (see GPrint)
  1467. Source:        smalltxt.asm (f8x8.asm, $graph.asm)
  1468.  
  1469. Call with:     no parameters
  1470. Returns:       nothing
  1471. Uses:          nothing; all registers and flags are saved
  1472. Example:
  1473.  
  1474. include asm.inc
  1475.  
  1476. extrn   smalltext:proc, stdtext:proc
  1477.  
  1478. .code
  1479.         .
  1480.         .
  1481.         .
  1482. ; make GPrint use the small 8x8 characters
  1483. ; make sure high ASCII characters are available
  1484.         call   smalltext
  1485.         .
  1486.         .
  1487.  
  1488. ; sometime later, I want to use larger 8x14 characters
  1489.         call   stdtext
  1490.  
  1491.  
  1492. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1493.  
  1494. UC2SYS:        convert user-defined coordinates to system coordinates
  1495. Source:        uc2sys.asm ($graph.asm)
  1496.  
  1497. Call with:     DS:[BX] pointing to (x0,y0,x1,y1) coordinates in
  1498.                user-defined format
  1499.                assumes DS:@data
  1500. Returns:       DS:[BX] pointing to (x0,y0,x1,y1) coordinates in system
  1501.                format
  1502.                UCINIT and UC2SYS allow the programmer to define a
  1503.                graph coordinate system to fit the data, and converts
  1504.                the system's y-orientation from top-to-bottom to the more
  1505.                familiar bottom-to-top
  1506.                US2SYS maintains a separate data area for converted
  1507.                coordinates; the input coordinates are not changed
  1508. Uses:          BX
  1509. Supports:      all ASMLIB graphics modes; user-defined coordinates
  1510.                from -32767 to +32767; see also UCINIT
  1511. Example:       see UCINIT
  1512.  
  1513.  
  1514. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1515.  
  1516. UCINIT:        specify user-defined coordinates
  1517. Source:        uc2sys.asm ($graph.asm)
  1518.  
  1519. Call with:     DS:[BX] pointing to desired xmin, ymin, xmax, ymax
  1520.                coordinates (xmax-xmin < 32767, ymax-ymin < 32767)
  1521.                assumes DS:@data
  1522.                ASMLIB's default user coordinates are (0,0,1000,1000)
  1523. Returns:       nothing
  1524. Uses:          nothing
  1525. Example:
  1526.  
  1527. ; I'm plotting a graph on the screen with x-axis data from 1983 to 2007
  1528. ; and y-axis data from -72 to 140
  1529. ; I'll leave some space on each side for titles, etc.
  1530.  
  1531. extrn   ucinit:proc, uc2sys:proc
  1532. extrn   drawbox:proc
  1533.  
  1534. .data
  1535. x0      dw 1975    ; xmin
  1536. y0      dw -80     ; ymin
  1537. x1      dw 2014    ; xmax
  1538. y1      dw 148     ; ymax
  1539.  
  1540. .code
  1541. ; program fragment assumes DS:@data
  1542.         .
  1543.         .
  1544.         .
  1545. ; establish coordinates
  1546.         lea     bx,x0
  1547.         call    ucinit
  1548.  
  1549. ; draw a box arouund the graph
  1550.         mov     x0,1983
  1551.         mov     y0,-72
  1552.         mov     x1,2007
  1553.         mov     y1,140
  1554.         lea     bx,x0
  1555.         call    uc2sys
  1556.         call    drawbox
  1557.  
  1558. ; SEE ALSO BARGRAPH.ASM EXAMPLE PROGRAM
  1559.  
  1560.  
  1561. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1562.  
  1563. USEGPAGE:      changes active graphics page used by ASMLIB
  1564.                does not change page displayed (see GPage and ShowGPage)
  1565. Source:        gpage.asm ($graph.asm, $herc.asm)
  1566.  
  1567. Call with:     BL = page number
  1568. Returns:       if CF = 0, no error
  1569.                if CF = 1, bad page number
  1570. Uses:          CF
  1571. Supports:      HGraph (mono and InColor) with Use64k
  1572.                EGA and VGA: modes with more than one page
  1573. Example:
  1574.  
  1575. include asm.inc
  1576.  
  1577. extrn   usegpage:proc
  1578.  
  1579. .code
  1580.         .
  1581.         .
  1582.         mov   bl,1
  1583.         call  usegpage
  1584.         jc    oops
  1585.  
  1586.  
  1587.  
  1588. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1589.  
  1590. VIEWLIMIT:     determine current mode's maximum dimensions
  1591. Source:        view.asm ($graph.asm)
  1592.  
  1593. Call with:     no parameters
  1594. Returns:       ES:[BX] pointing to xmax
  1595.                ES:2[BX] pointing to ymax
  1596. Uses:          ES, BX
  1597. Supports:      all ASMLIB graphics modes
  1598. Example:
  1599.  
  1600. include asm.inc
  1601.  
  1602. extrn   viewlimit:proc
  1603.  
  1604. .code
  1605.         .
  1606.         .
  1607.         call  viewlimit
  1608.  
  1609.